package lumis.portal.webfilereplication;

import lumis.portal.filesystem.PortalFile;

/**
 * Performs a file replication, updating a destination according changes in 
 * the portal file system.
 * <p>
 * The life cycle of the file replicator is:
 * <ol>
 * <li>
 * The IFileReplicator implementation is instantiated using its no-args
 * constructor.
 * </li>
 * <li>
 * The method {@link #setWebFileReplication(WebFileReplication)} is called
 * providing informations about the replication to be done.
 * </li>
 * <li>
 * The {@link #initialize()} method is called.
 * </li>
 * <li>
 * Multiple calls to {@link #write(PortalFile)} or {@link #delete(PortalFile)}
 * methods may occur.
 * </li>
 * <li>
 * The method {@link #dispose()} is called. This method will be called even
 * if a {@link #write(PortalFile)} or {@link #delete(PortalFile)} operation
 * resulted in a exception.
 * </li>
 * </ol>
 * 
 * <p>
 * Consider using {@link AbstractFileReplicator} as a base class when 
 * implementing a IFileReplicator, for easiness and better future compatibility.
 * 
 * @version $Revision: 13093 $ $Date: 2011-05-28 18:40:18 -0300 (Sat, 28 May 2011) $
 * @since 6.0.0
 */
public interface IFileReplicator
{
	/**
	 * Provides replication information.
	 * 
	 * @param replication the WebFileReplication that contains information about the 
	 * next replication to be processed.
	 * @since 6.0.0
	 */
	public void setWebFileReplication(WebFileReplication replication);
	
	/**
	 * Initializes this file replicator.
	 * 
	 * @throws FileReplicationException if a problem prevents the file 
	 * replication to be done.
	 * 
	 * @since 6.0.0
	 */
	public void initialize() throws FileReplicationException;

	/**
	 * Writes a file or directory on the replication destination.
	 * <p>
	 * If the given file {@link PortalFile#isDirectory() is a directory}, 
	 * this operation must create the corresponding directory in the 
	 * destination if it does not already exist.
	 * <p>
	 * If the given file {@link PortalFile#isFile() is a normal file}, 
	 * this operation must create the corresponding file in the destination, 
	 * with the same contents, overwriting the file if it already exists. 
	 * <p>
	 * This operation must create any non-existant parent directories necessary
	 * for creating the corresponding directory/file in the destination.
	 * <p>
	 * This write operation need not to be completed when this method returns,
	 * but it must be completed before the next call to {@link #dispose()}
	 * returns.
	 * 
	 * @param file the corresponding file in the portal file system.
	 * 
	 * @throws FileReplicationException if a problem prevents the file 
	 * replication to be done.
	 * 
	 * @since 6.0.0
	 */
	public void write(PortalFile file) throws FileReplicationException;

	/**
	 * Removes a file or directory from the replication destination.
	 * <p>
	 * If the given file is a directory and it is not empty at the destination,
	 * this operation should fail throwing FileReplicationException. 
	 * <p>
	 * If the corresponding file in the destination does not exist, this 
	 * operation must be a no-op and complete gracefully.
	 * <p>
	 * This delete operation need not to be completed when this method returns,
	 * but it must be completed before the next call to {@link #dispose()}
	 * returns.
	 * 
	 * @param file the corresponding file in the portal file system.
	 * 
	 * @throws FileReplicationException if a problem prevents the file 
	 * replication to be done.
	 * 
	 * @since 6.0.0
	 */
	public void delete(PortalFile file) throws FileReplicationException;
	
	/**
	 * Allows the replicator to complete pending operation and free any 
	 * used resources.
	 * <p>
	 * After this method is called, the replicator will not be used anymore,
	 * unless it is reinitialized.
	 * 
	 * @throws FileReplicationException if a problem prevents pending file 
	 * replications to be done. Even if this exception is thrown, the replicator
	 * must free any allocated resource.
	 * 
	 * @since 6.0.0
	 */
	public void dispose() throws FileReplicationException;
}
